﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Logging</title>
  <keywords>
    <keyword translate="true">Diagnostics</keyword>
    <keyword translate="true">Logging</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Logging</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Starting with version 2.2, Catel uses a custom internal logging system. This way, the reference to </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://logging.apache.org/log4net/" target="_blank" styleclass="Normal" style="font-style:normal;" translate="true">log4net</link><text styleclass="Normal" translate="true"> could be removed. The idea behind this move is not to force the user to use </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://logging.apache.org/log4net/" target="_blank" styleclass="Normal" style="font-style:normal;" translate="true">log4net</link><text styleclass="Normal" translate="true">. Also, </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://logging.apache.org/log4net/" target="_blank" styleclass="Normal" style="font-style:normal;" translate="true">log4net</link><text styleclass="Normal" translate="true"> seems deprecated (no new releases for a long time), and other logging systems such as </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://nlog-project.org/" target="_blank" styleclass="Normal" translate="true">NLog</link><text styleclass="Normal" translate="true"> seem to grow in popularity.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The new logging system only allows very basic logging. This way, the logging is kept very simple and the real logging can be implemented by the end-developer if he/she feels the need for it.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Log and ILog</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">All logging is available via the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Logging_ILog" styleclass="Normal" translate="true">ILog</link><text styleclass="Normal" translate="true"> interface. This interface is registered automatically on all objects in Catel as </text><text styleclass="Normal" style="font-style:italic;" translate="true">Log</text><text styleclass="Normal" style="font-style:normal;" translate="true"> field. This way, every object can log any information by calling methods on the </text><text styleclass="Normal" style="font-style:italic;" translate="true">Log</text><text styleclass="Normal" style="font-style:normal;" translate="true"> field.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" style="font-style:normal;" translate="true">In Catel, there is only one implementation of the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Logging_ILog" styleclass="Normal" translate="true">ILog</link><text styleclass="Normal" style="font-style:normal;" translate="true"> interface, which is the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Logging_Log" styleclass="Normal" style="font-style:normal;" translate="true">Log</link><text styleclass="Normal" style="font-style:normal;" translate="true"> class. This class makes sure that the log messages are formatted correctly and the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="E_Catel_Logging_ILog_LogMessage" styleclass="Normal" style="font-style:normal;" translate="true">LogMessage</link><text styleclass="Normal" style="font-style:normal;" translate="true"> event is invoked when a message is written to the log.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" style="font-style:normal;" translate="true">Catel internally creates a separate log per type. This way, there will be lots of logs and it should be easy to filter the information the end-developer is really interested in.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">LogManager</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Logging_LogManager" styleclass="Normal" translate="true">LogManager</link><text styleclass="Normal" translate="true"> is the class where it all comes together. This class is responsible for creating new logs for types, but also keeps track of all logs and log listeners. To retrieve the log for a specific class, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">private</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">static</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">readonly</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">ILog</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Log</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">LogManager.GetCurrentClassLogger();</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Logging in code</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To log in code, the ILog interface implements some basic methods to log information with an option for extra data. There are however lots of extension methods available to log exceptions, string formats and more. Below is an example of logging in code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" translate="true">Log.Warning(&quot;Customer &apos;{0}&apos; does not exist&quot;,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">customerId);</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Or, if an exception is available, this can written to the log as well.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" translate="true">Log.Error(ex, &quot;Failed to delete file &apos;{0}&apos;&quot;,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">fileName);</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Logging to the output window or console</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">By default, Catel does not add any listeners. However, it contains a ready-to-use implementation that writes all logs to the output window or console, which is the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Logging_DebugLogListener" styleclass="Normal" translate="true">DebugLogListener</link><text styleclass="Normal" translate="true">. To register this listener, call this at any time:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">LogManager.RegisterDebugListener();</text></para>
  </body>
</topic>
